/* libfake437 - a library for the rendering of code page 437 `graphics'
 * Copyright (C) 2008, 2009 Jack Kelly <endgame.dos@gmail.com>
 *
 * This library is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation, either version 3 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 ** @node F437Surface Operations
 ** @chapter F437Surface Operations
 **
 ** The @code{F437Surface} allows simplified writing of large numbers
 ** of characters to an @code{SDL_Surface}.
 **/

#ifndef FAKE437_SURFACE_H
#define FAKE437_SURFACE_H

#ifdef __cplusplus
extern "C"{
#endif

/**
 ** @deftypefun F437Surface* f437_surface_new @
 **   (SDL_Surface* @var{surface})
 **
 ** Creates a @code{F437Surface} that is centred within @var{surface}
 ** and is as wide and as tall as possible while still able to fit
 ** within @var{surface}. It should be freed with
 ** @code{f437_surface_free} when no longer needed. An
 ** @code{F437Surface} assumes no ownership of any @code{SDL_Surface}
 ** it comes in contact with, and @var{surface} must have a longer
 ** lifespan than the returned @code{F437Surface*}. This function calls
 ** @code{abort} if there is an allocation failure.
 **
 ** @end deftypefun
 **/
F437Surface* f437_surface_new(SDL_Surface* surface);

/**
 ** @deftypefun void f437_surface_free @
 **   (F437Surface* @var{surface})
 **
 ** Frees a @code{F437Surface}, but not the @code{SDL_Surface} it was
 ** pointing to.
 **
 ** @end deftypefun
 **/
void f437_surface_free(F437Surface* surface);

/**
 ** @deftypefun void f437_surface_put_char @
 **   (F437Surface*     @var{surface},     @
 **    int              @var{left},        @
 **    int              @var{top},         @
 **    int              @var{ch},          @
 **    const SDL_Color* @var{fg},          @
 **    const SDL_Color* @var{bg})
 **
 ** @deftypefunx void f437_surface_put_rect @
 **   (F437Surface*     @var{surface},      @
 **    int              @var{left},         @
 **    int              @var{top},          @
 **    int              @var{width},        @
 **    int              @var{height},       @
 **    int              @var{ch},           @
 **    const SDL_Color* @var{fg},           @
 **    const SDL_Color* @var{bg})
 **
 ** @deftypefunx void f437_surface_put_string @
 **   (F437Surface*     @var{surface},        @
 **    int              @var{left},           @
 **    int              @var{top},            @
 **    const char*      @var{string},         @
 **    const SDL_Color* @var{fg},             @
 **    const SDL_Color* @var{bg})
 **
 ** These functions are similar to their counterparts in
 ** @ref{Primitive Operations}, except that @var{left} and @var{top}
 ** define offsets in characters instead of pixels.
 **
 ** @end deftypefun
 **/
void f437_surface_put_char(F437Surface* surface, int left, int top, int ch,
                           const SDL_Color* fg, const SDL_Color* bg);
void f437_surface_put_rect(F437Surface* surface, int left, int top,
                           int width, int height, int ch,
                           const SDL_Color* fg, const SDL_Color* bg);
void f437_surface_put_string(F437Surface* surface, int left, int top,
                             const char* string,
                             const SDL_Color* fg, const SDL_Color* bg);

#ifdef __cplusplus
}
#endif

#endif
